Skip to content

docs: shorten the README and add a map of where things are #192

Jump to bottom
Merged
merged 2 commits into from
Nov 10, 2026
Merged

docs: shorten the README and add a map of where things are #192

merged 2 commits into from
Nov 10, 2026
+312 −278

Conversation

ronjalh
Copy link
Member

@ronjalh ronjalh commented Nov 10, 2026

What

The README was about 59 kB, which the peer feedback (#167) found hard to find your way in. It is now about half the size, and no reasoning is deleted.

  • Four long sections moved unchanged to their own documents, each with a short summary and a link left in the README: docs/ELEMENTS_PAGE.md, docs/DATABASE_SETUP.md, docs/CATALOG_SEARCH.md, docs/E2E_TESTS.md.
  • A new "Where is what" table in the README: for each feature (the database search, the Elements page, the gymnast pages, login, the D-score, the schema, the tests) the file where it starts and the document with more.
  • A list of contents at the top of docs/API.md.
  • A short entry in docs/AI_USAGE.md.

Checked

  • A script checked every relative link and anchor in the changed files; the only broken one is IMAGES.md in docs/API.md, which is broken on dev too.
  • The headings of the moved sections went one level up (they are titles of their own files now), and the relative links in them were adjusted.
  • The text was moved and not rewritten, so what is outdated in it is still outdated (see Update docs #148).

Closes #182

🤖 Generated with Claude Code

docs: shorten the README and add a map of where things are
3cbcaa6 
Move the sections on the Elements page, the database setup, the catalog
search and the end-to-end tests to docs/ unchanged, with a short summary
and a link in the README. Add a Where is what table and a list of
contents to docs/API.md.

Closes #182
@ronjalh ronjalh requested a review from a team as a code owner November 10, 2026 19:37
@ronjalh ronjalh self-assigned this Nov 10, 2026
Base automatically changed from dev to main November 10, 2026 19:45
@ronjalh ronjalh changed the base branch from main to dev November 10, 2026 19:48
xeniag
xeniag approved these changes Nov 10, 2026
View reviewed changes
Copy link
Member

@xeniag xeniag left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@xeniag xeniag merged commit b07cf9b into dev Nov 10, 2026
@xeniag xeniag deleted the 182-shorter-readme-with-an-overview branch November 10, 2026 19:54
@ronjalh ronjalh mentioned this pull request Nov 10, 2026
Open
Sign in to join this conversation on GitHub.
Reviewers

@xeniag xeniag xeniag approved these changes

Assignees

@ronjalh ronjalh

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

docs: a shorter README with an overview and links, and a map of where the search is
2 participants
@ronjalh @xeniag